home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / maximus / flist21.zip / FLIST.DOC < prev    next >
Text File  |  1992-08-26  |  10KB  |  225 lines
  1.  
  2. FLIST -- Generates file lists based on privilege levels and keys
  3.  
  4. Version 2.1  (8/26/92)
  5.  
  6. Written by Bob Quinlan of Austin, Texas, USA
  7. Sysop of Red October at 512-834-2593 (1:382/111)
  8.  
  9. Copyright 1992 by Bob Quinlan
  10.  
  11. Compatible with Maximus 2.00 and 2.01
  12.  
  13.  
  14. Special thanks to David Powers for encouragement, ideas, and code!
  15.  
  16.  
  17. This program generates a list of files that a user with a particular
  18. privilege level and set of keys could access.  It is intended to make
  19. the procedure independent of changes to the structure of your file
  20. areas.  Instead of specifying which areas should be included you just
  21. specify what sort of user you want the list to apply to.
  22.  
  23. You can also create lists of new files.  Just use /D to specify how many
  24. days of files you want to list.
  25.  
  26.     /Afile      Area file.  You can use this to specify a path to
  27.                 AREA.DAT or to refer to another file (although it must
  28.                 follow the AREA.DAT format).  The filename must be
  29.                 included along with the path.  Defaults to AREA.DAT in
  30.                 the current directory.
  31.  
  32.     /B          Include barricaded areas.  If this switch is not
  33.                 included no barricaded areas will be included.
  34.  
  35.     /C          Include comments from the FILES.BBS file lists.  By
  36.                 default only files and their descriptions are included.
  37.  
  38.                 Using this switch has one side-effect!  Normally area
  39.                 headers are only generated for areas that have files in
  40.                 them.  /C will cause them to be generated for any area
  41.                 that has comments as well.  Do not use /C if you only
  42.                 want areas that have files in them to appear!  (I
  43.                 recommend not using /C with /D so that you don't show
  44.                 lots of apparently empty file areas.)
  45.  
  46.     /Ddays      Days.  Excludes all files more than this many days old.
  47.                 Use this switch to create lists of new files.
  48.  
  49.     /Ffile      Output file.  The pathname of the file you want the file
  50.                 list written to.  Defaults to FLIST.TXT in the current
  51.                 area.
  52.  
  53.     /HAfile     Area header file.  The contents of this file will be
  54.                 added to the report for each area header.  There are
  55.                 several sequences you can embed in the file that have
  56.                 special meanings:
  57.  
  58.                     %N will be replaced with the area name.
  59.                     %I will be replaced with the area information.
  60.                     %D will be replaced with the report date.
  61.                     %T will be replaced with the report time.
  62.                     %A will be replaced with the age of the files
  63.                        included in the report.  Do not use this except
  64.                        with the /D command line parameter!
  65.  
  66.                     Any of these may be followed by an L, R, or C
  67.                     immediately followed by a number.  These will left,
  68.                     right, or center justify the value in a field of the
  69.                     specified width.
  70.  
  71.                     You can also follow any of the above with an NF or
  72.                     with an Fx.  NF stands for "no fill" and has no
  73.                     effect (see examples).  Fx stands for "fill" and
  74.                     will cause the entire field to be replaced by an
  75.                     equivalent number of the character 'x'.  This is
  76.                     useful when drawing boxes.
  77.  
  78.                 This switch is not required.  If no area header file is
  79.                 specified a default header will be used.
  80.  
  81.     /HBfile     Beginning header file.  The contents of this file will
  82.                 be added to the beginning of the report.  There are
  83.                 several sequences you can embed in the file that have
  84.                 special meanings.  All of the codes listed under /HA are
  85.                 allowed except for %N and %I.
  86.  
  87.     /HEfile     End header file.  The contents of this file will be
  88.                 added to the end of the report.  There are several
  89.                 sequences you can embed in the file that have special
  90.                 meanings.  All of the codes listed under /HA are allowed
  91.                 except for %N and %I.
  92.  
  93.     /Kkeys      Keys to use for access to locked areas.  Keys are
  94.                 represented by 1-8 and A-X.  An asterisk (*) turns on
  95.                 all of the keys.  Multiple keys can be specified in one
  96.                 /K argument (such as /K12B).
  97.  
  98.     /N          No-wrap.  Leave long description lines intact.  The
  99.                 default is to wrap them.
  100.  
  101.     /O          Include offline files.  By default files that are listed
  102.                 but not present are not included in the list.
  103.  
  104.     /Ppriv      Privilege to use for access to areas.  Only the first
  105.                 letter of the level name is required.  Legal values are:
  106.                     Twit
  107.                     Disgrace
  108.                     Limited
  109.                     Normal
  110.                     Worthy
  111.                     Privil
  112.                     Favored
  113.                     Extra
  114.                     Clerk
  115.                     AsstSysop
  116.                     Sysop
  117.                     Hidden
  118.                 Defaults to Normal.
  119.  
  120.     /Q          Quiet.  Eliminates the progress display.
  121.  
  122.     /T          Truncate long description lines.  The default is to wrap
  123.                 them.
  124.  
  125. Let me show you an example of how to use the %N and %I parameters in an
  126. area header file (defined with the /HA switch).  The purpose of those
  127. parameters is to let you build boxes that will conform to the size of
  128. the text produced by %N and %I.  Here is an example of a simple header
  129. box using these parameters:
  130.  
  131. ┌──%NF───┬──%IF───┐
  132. │  %NNF  │  %INF  │
  133. └──%NF───┴──%IF───┘
  134.  
  135. Note that the characters following the %NF and %IF look like a part of
  136. the regular text, but are actually the characters that will be used to
  137. fill out the parameters to the desired length.
  138.  
  139. This will expand to something that looks like this:
  140.  
  141. ┌───────┬───────────────────────────────────────────┐
  142. │  MAX  │  Maximus BBS files and related utilities  │
  143. └───────┴───────────────────────────────────────────┘
  144.  
  145. Now you can see why the apparently useless NF modifier can be useful. It
  146. pads out the shorter embedded codes so that they visually match those in
  147. the surrounding lines.  The following would produce exactly the same
  148. result as the previous example, but it is a lot harder to figure out how
  149. everything will match up:
  150.  
  151. ┌──%NF───┬──%IF───┐
  152. │  %N  │  %I  │
  153. └──%NF───┴──%IF───┘
  154.  
  155. Here is an example using fixed width fields.  This also right justifies
  156. the area name and left justifies the area information:
  157.  
  158. ┌─%NR9F──┬─%IL50F──┐
  159. │ %NR9NF │ %IL50NF │
  160. └─%NR9F──┴─%IL50F──┘
  161.  
  162. Which will expand to something that looks like this:
  163.  
  164. ┌───────────┬────────────────────────────────────────────────────┐
  165. │       MAX │ Maximus BBS files and related utilities            │
  166. └───────────┴────────────────────────────────────────────────────┘
  167.  
  168.  
  169. FLIST returns the following ERRORLEVELS:
  170.     0 = success
  171.     1 = bad command line parameter
  172.     2 = unable to open AREA.DAT
  173.     3 = unable to open header file
  174.     4 = unable to open output file
  175.     5 = not enough memory to run
  176.     6 = string overflow processing header
  177.  
  178. NOTICE:  You may use, copy, and distribute this program freely as long
  179. as you insure that both the executable and the documentation (.DOC)
  180. files are included in the distribution package.  The source code does
  181. not need to be included.  You may modify this program and document, so
  182. long as reasonable credit is given to the original author if a
  183. substantial portion of the original remains intact.  The author is not
  184. responsible for any losses which may occur either directly or indirectly
  185. as a result of using this program.
  186.  
  187. This program uses the Maximus structures written by Scott J. Dudley.
  188.  
  189. HISTORY:
  190. Version 2.1   (8/26/92) -- Added the /Q switch to eliminate the progress
  191.                            display.  Now returns different errorlevels
  192.                            for each possible error.  Fixed problem with
  193.                            headers before comments.
  194. Version 2.0   (8/23/92) -- Added more error checking.
  195. Version 1.9   (8/22/92) -- Added a progress display.  Fixed a memory
  196.                            corruption bug.
  197. Version 1.8   (8/20/92) -- Added fixed width fields with left, right,
  198.                            and centered justification for embedded
  199.                            variables.  Changed the previous codes for
  200.                            embedded variables!  Removed built-in help to
  201.                            reduce memory requirements.
  202. Version 1.7   (8/10/92) -- Added embedded variables to the begin and end
  203.                            headers.  Note: This eliminated the automatic
  204.                            file age comment that used to be included for
  205.                            newfile lists.
  206. Version 1.6   (8/10/92) -- Added the /HA option to allow customized area
  207.                            headers in the report.  This is an expansion
  208.                            of an idea and code by David Powers.
  209. Version 1.5   (8/09/92) -- Added the /HB and /HE options to allow
  210.                            customized beginning and end text in the
  211.                            report.  Added /? help option to print the
  212.                            parameter list.  Added a clearer explanation
  213.                            of /C's effect on area headers.
  214. Version 1.4   (8/07/92) -- Added the /C option to include file list
  215.                            comments.  Added code to recognize free
  216.                            switches so they do not show up in the
  217.                            descriptions.  Fixed error if first entry in
  218.                            AREA.DAT did not include a file area.
  219. Version 1.3   (8/06/92) -- Read the file list filename from AREA.DAT
  220.                            instead of assuming FILES.BBS.
  221. Version 1.2   (8/02/92) -- Added days header for new files list.
  222. Version 1.1   (7/30/92) -- Added file age cutoff.
  223. Version 1.0   (6/30/92) -- Original release.  Written in Borland C.
  224.  
  225.